Skip to content

feat(core): MCP server instrumentation without breaking Miniflare #16817

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 61 commits into
base: develop
Choose a base branch
from

Conversation

betegon
Copy link
Member

@betegon betegon commented Jul 4, 2025

Closes #16826, #16654, #16666 #16978

Different approach from #16807 .

Using Proxy was causing issues in cloudflare #16182.

Now using fill we shouldn't have those problems as fill doesn't create a new wrapper object with a different identity, so now:

  1. fill just replaces the method on the existing object
  2. The transport object keeps its original identity
  3. When transport.start() runs and accesses private fields, this is still the original transport object
  4. The WeakMap recognizes it as the same object that owns the private fields

What's inside

  • Support for new MCP SDK methods (mcpServerInstance.tool(), mcpServerInstance.resource(), etc.)
  • Tracing instrumentation
  • Error handling

Tracing

It follows OTEL semantic conventions for MCP and adds more attributes we thought are useful.

It also handles PII based on user setting of sendDefaultPii.

Tracing flow

  1. Transport receives tools/call request (id: 2)
  2. Create INACTIVE mcp.server span
  3. Store span inrequestIdToSpanMap[2] = { span, method: "tools/call", startTime }
  4. Execute handler with span context (handler gets requestId: 2)
  5. Handler finds span using requestId: 2
  6. Tool execution happens within span context
  7. Response sent with tool results
  8. completeSpanWithToolResults(2, result) enriches and completes span

Error handling

  1. error capture - errorCapture.ts
  • Non-invasive error reporting that never interferes with MCP service operation
  • Error context with MCP-specific metadata
  • PII filtering respects sendDefaultPii settings
  • Resilient to Sentry failures (wrapped in try-catch)
  1. Tool execution error capturing - handlers.ts
  • Captures exceptions thrown during tool execution
  • Preserves normal MCP behaviour (errors converted to isError: true)
  • Includes tool name, arguments, and request context
  • Handles both sync and async tool handlers
  1. Transport error instrumentation - transport.ts
  • Captures connection errors and network failures
  • Intercepts JSON-RPC error responses
  • Includes transport type and session information
  • Handles error responses being sent back to clients

betegon added 24 commits June 27, 2025 20:46
…ibute names to match OTEL draft semantic convention
@betegon betegon self-assigned this Jul 4, 2025
@betegon betegon requested a review from AbhiPrasad July 4, 2025 18:28
@betegon betegon changed the title Bete/mcp server semantic convention fill feat(core): MCP server instrumentation without breaking Miniflare Jul 4, 2025
Copy link
Member

@AbhiPrasad AbhiPrasad left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very nice, all good from my eyes in overall direction!

@betegon
Copy link
Member Author

betegon commented Jul 7, 2025

Thanks @AbhiPrasad! Will keep working on this and close the other PR using Proxy. Will apply your suggestions here!

@AbhiPrasad
Copy link
Member

only work if the transport methods are defined at connect() time, and that the fill doesn’t capture handlers set lazy after that

yeah as long as it exists when we wrap it I think we are fine.

cursor[bot]

This comment was marked as outdated.

cursor[bot]

This comment was marked as outdated.

cursor[bot]

This comment was marked as outdated.

cursor[bot]

This comment was marked as outdated.

cursor[bot]

This comment was marked as outdated.

@betegon betegon requested a review from AbhiPrasad July 22, 2025 08:59
@betegon
Copy link
Member Author

betegon commented Jul 22, 2025

@AbhiPrasad just finished suggested changes + added some new stuff:

  • Session data: information to persist during a session. this includes MCP protocol version, client name, server name, etc. The idea is to be extensible for new fields as the protocol changes. closes MCP Server - instrument user_agent header from MCP clients #16978
  • Fix span status to be set as internal_error when an error occurs.
  • Added the mechanism to avoid using tags
  • Capture only JSON-RPC server side errors (so we don't report client side errors here).

@betegon betegon requested a review from mydea July 24, 2025 12:01
betegon added a commit to getsentry/sentry-docs that referenced this pull request Jul 25, 2025
## DESCRIBE YOUR PR

Closes #14106

Adds developer docs for our MCP Server instrumentation. 

Route for the documentation `sdk/expected-features/mcp-instrumentation`
that includes:

```bash
.mcp-instrumentation
├── index.mdx  # brief description on current features and limitations
├── errors.mdx # draft errors doc 
└── tracing.mdx # Tracing and span conventions
```

Followed this file structure as a start to (in the future) have this
structure for all the other features, having something like this below,
where we have :
```
.[Feature 1]
├── index.mdx 
├── logs.mdx 
├── errors.mdx 
.
.
.
.[Feature 2]
├── index.mdx 
├── errors.mdx 
├── tracing.mdx
.
.
.
 ```

The structure idea is from @abhi, who helped me settle this <3.

**NOTE:** Error docs are going to change, addressing feedback from [sentry-javascript/pull/16817](getsentry/sentry-javascript#16817)

## IS YOUR CHANGE URGENT?  


## PRE-MERGE CHECKLIST

*Make sure you've checked the following before merging your changes:*

- [x] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs)

---------

Co-authored-by: Alex Krawiec <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

MCP Server tracing instrumentation
2 participants